Music Component Functions: Instruments and Parts19

The functions described in this section initialize a part with an instrument, store instruments, list available instruments, manipulate parts, and get information about parts.

MusicGetPartInstrumentNumber

The MusicGetPartInstrumentNumber function returns the instrument number currently assigned to that part.



 
pascal ComponentResult MusicGetPartInstrumentNumber( 

                     MusicComponent mc, 

                     long part);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part number containing instrument.
function result: A positive return value is the instrument number; a negative value is a result code.

MusicSetPartInstrumentNumber

The MusicSetPartInstrumentNumber function initializes a part with a particular instrument.



 
pascal ComponentResult MusicSetPartInstrumentNumber( 

                     MusicComponent mc, 

                     long part, 

                     long instrumentNumber);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part to be initialized.
instrumentNumber: Number of instrument to initialize part with.
function result: A result code.

DISCUSSION

You can use the MusicFindTone function MusicFindTone to find out an instrument number.

This function is superseded by MusicSetPartInstrumentNumberInterruptSafe , which can be called at interrupt time. You cannot call MusicGetPartInstrumentNumber at interrupt time.

MusicSetPartInstrumentNumberInterruptSafe

The MusicSetPartInstrumentNumberInterruptSafe function initializes a part with a particular instrument.



 
pascal ComponentResult MusicSetPartInstrumentNumber( 

                     MusicComponent mc, 

                     long part, 

                     long instrumentNumber);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part to be initialized.
instrumentNumber: Number of instrument to initialize part with.
function result: A result code.

DISCUSSION

You can use the MusicFindTone function MusicFindTone to find out an instrument number.

You can call the MusicSetPartInstrumentNumberInterruptSafe function at interrupt time.

MusicGetPartAtomicInstrument

The MusicGetPartAtomicInstrument function returns the atomic instrument currently in a part.



 
extern pascal ComponentResult MusicGetPartAtomicInstrument(

                     MusicComponent mc,

                     long part,

                     AtomicInstrument *ai,

                     long flags)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The part with the atomic instrument.
ai: On exit, an atomic instrument.
flags: Specify what pieces of information about an atomic instrument the caller is interested in. Atomic Instrument Information Flags
function result: A result code.

MusicSetPartAtomicInstrument

The MusicSetPartAtomicInstrument function initializes a part with an atomic instrument.



 
extern pascal ComponentResult MusicSetPartAtomicInstrument(

                     MusicComponent mc,

                     long part,

                     AtomicInstrumentPtr aiP,

                     long flags)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The part to initialize with the atomic instrument to.
aiP: The atomic instrument.
flags: These flags specify details of initializing a part with an atomic instrument. Flags for Setting Atomic Instruments
function result: A result code.

MusicStorePartInstrument

The MusicStorePartInstrument function puts whatever instrument is on the specified part into the synthesizer's instrument store. This enables you to store modified instruments.



 
pascal ComponentResult MusicStorePartInstrument( 

                     MusicComponent mc,

                     long part, 

                     long instrumentNumber);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part containing the instrument to be stored.
instrumentNumber: Instrument number at which to store the part.
function result: A result code.

DISCUSSION

The value of the InstrumentNumber parameter must be between 1 and the synthesizer's modifiable instrument count, as defined by the modifiableInstrumentCount field of the synthesizer's description record.

MusicGetInstrumentAboutInfo

The MusicGetInstrumentAboutInfo function gets the information about an instrument that appears in its About box.



 
pascal ComponentResult MusicGetInstrumentAboutInfo(

                     MusicComponent mc,long part, 

                     InstrumentAboutInfo *iai);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Number of the part containing the instrument for which you want information.
*iai: On exit, a pointer to an instrument About information structure Instrument About Information for the instrument currently on the specified synthesizer part.

MusicGetInstrumentInfo

The MusicGetInstrumentInfo function gets a list of instruments supported by a synthesizer. It also gets the names of the instruments.



 
extern pascal ComponentResult MusicGetInstrumentInfo(

                     MusicComponent mc,

                     long getInstrumentInfoFlags,

                     InstrumentInfoListHandle *infoListH)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
getInstrumentInfoFlags: Use these flags to specify whether you want a list of fixed instruments, modifiable instruments, or all instruments. See "Instrument Info Flags" .
infoListH: On exit, the list of instruments Instrument Information List .
function result: A result code.

This handle must be disposed of by the caller.

DISCUSSION

The functions takes a music component in the mc parameter and instructions regarding which types of instruments to get information for in the flags parameter. It returns a handle to an instrument information list in the *infoListH parameter.

MusicGetPart

The MusicGetPart function returns the MIDI channel and maximum polyphony for a particular part in the *MIDIChannel and *polyphony parameters.



 
pascal ComponentResult MusicGetPart(

                     MusicComponent mc, 

                     long part, 

                     long *MIDIChannel, 

                     long *polyphony)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The music component part requested.
*MIDIChannel: Pointer to long for MIDIChannel result.
*polyphony: Pointer to long for polyphony result.
function result: A result code.

DISCUSSION

For non-MIDI devices, the MIDI channel pointed to by the MIDIChannel parameter is 0.

MusicSetPart

The MusicSetPart function sets the MIDI channel and maximum polyphony for the specified part to the values in the MIDIChannel and polyphony parameters.



 
pascal ComponentResult MusicSetPart(

                     MusicComponent mc, 

                     long part, 

                     long MIDIChannel, 

                     long polyphony)

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part whose MIDI channel and polyphony are to be set.
MIDIChannel: The MIDI channel to set the part to.
polyphony: The maximum voices or polyphony for the part.
function result: A result code.

DISCUSSION

For non-MIDI devices, set the MIDI channel pointed to by the MIDIChannel parameter to 0.

MusicGetPartName

The MusicGetPartName function returns the string name of a part.



 
pascal ComponentResult MusicGetPartName(

                     MusicComponent mc,

                     long part, 

                     StringPtr name);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part to get name of.
name: On exit, the string containing the part name.
function result: A result code.

DISCUSSION

The name string is used by selection dialogs or configuration information.

MusicSetPartName

You can use the MusicSetPartName function to change the name of an instrument in a specified part. For example, you might want to change the name of a modified instrument before saving it.



 
pascal ComponentResult MusicSetPartName(

                     MusicComponent mc,

                     long part, 

                     StringPtr name);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part to apply name to.
name: Name to apply to part.
function result: A result code.

DISCUSSION

The instrument name string is used by selection dialogs or in configuration information.

MusicGetPartKnob

The MusicGetPartKnob function gets the current value of a knob for a part.



 
pascal ComponentResult MusicGetPartKnob(

                     MusicComponent mc,

                     long part, 

                     long knobID);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The part number.
knobID: The knob index or ID.
function result: Positive or negative integers are knob values. Result codes are returned as0x8000xxxx , where xxxx is the result code.

MusicSetPartKnob

The MusicSetPartKnob function sets a knob for a specified part.



 
pascal ComponentResult MusicSetPartKnob(

                     MusicComponent mc,

                     long part, 

                     long knobID, 

                     long knobValue);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The part number.
knobNumber: The index or ID of the knob to be set.
knobValue: The value to set the knob to.
function result: A result code.

MusicResetPart

The MusicResetPart function silences all sounds on the specified part, and resets all controllers on that part to their default values. The default value is zero for all controllers except volume. Volume is set to its maximum 32767 or, in hexadecimal, 7F.FF .



 
pascal ComponentResult MusicResetPart(

                     MusicComponent mc, 

                     long Part);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: The number of the part.
function result: A result code.

MusicGetPartController

The MusicGetPartController function returns the value of the specified controller on the specified part.



 
pascal ComponentResult MusicGetPartController(

                     MusicComponent mc, 

                     long part, 

                     MusicController controllerNumber);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part whose controller value you want to get.
controllerNumber: Controller number.
function result: A result code.

MusicSetPartController

The MusicSetPartController function initializes the value of the specified controller on the specified part.



 
pascal ComponentResult MusicSetPartController(

                     MusicComponent mc, 

                     long part, 

                     MusicController controllerNumber, 

                     long controllerValue);

mc: Music component instance identifier returned by NAGetRegisteredMusicDevice .
part: Part to apply controller to.
controllerNumber: Controller number. For valid values see "Controller Numbers" .
controllerValue: Value for controller.
function result: A result code.

MusicSetPartSoundLocalization

The MusicSetPartSoundLocalization function passes sound localization data to a specified synthesizer part.



 
extern pascal ComponentResult MusicSetPartSoundLocalization(

                     MusicComponent mc,

                     long part,

                     Handle data)

mc: Music component instance identifier.
part: The part to pass the data to.
data: The sound localization data.
function result: A result code.